home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libelf / elf_begin.z / elf_begin
Encoding:
Text File  |  2002-10-03  |  12.9 KB  |  237 lines

  1. ELF_BEGIN(3E)                                         Last changed: 4-12-99
  2.  
  3.  
  4. NNAAMMEE
  5.      eellff__bbeeggiinn - Make a file descriptor
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_f_l_a_g ...] _f_i_l_e ...  --lleellff [_l_i_b_r_a_r_y ...]
  9.  
  10.      ##iinncclluuddee <<lliibbeellff..hh>>
  11.  
  12.      EEllff **eellff__bbeeggiinn((iinntt ffiillddeess,, EEllff__CCmmdd ccmmdd,, EEllff **rreeff));;
  13.  
  14. IIMMPPLLEEMMEENNTTAATTIIOONN
  15.      IRIX systems
  16.  
  17. DDEESSCCRRIIPPTTIIOONN
  18.      eellff__bbeeggiinn, eellff__nneexxtt, eellff__rraanndd, and eellff__eenndd work together to process
  19.      ELF object files, either individually or as members of archives.
  20.      After obtaining an ELF descriptor from eellff__bbeeggiinn, the program may read
  21.      an existing file, update an existing file, or create a new file.
  22.      ffiillddeess is an open file descriptor that eellff__bbeeggiinn uses for reading or
  23.      writing.  The initial file offset [see llsseeeekk(2)] is unconstrained, and
  24.      the resulting file offset is undefined.
  25.  
  26.      ccmmdd may have the following values:
  27.  
  28.      EELLFF__CC__NNUULLLL     eellff__bbeeggiinn returns a null pointer, without opening a new
  29.                     descriptor.  rreeff is ignored for this command.  See
  30.                     eellff__nneexxtt(3E) and the EXAMPLES section for more
  31.                     information.
  32.  
  33.      EELLFF__CC__RREEAADD     Specifies that the program examine the contents of an
  34.                     existing file.  Depending on the value of rreeff, this
  35.                     command examines archive members or entire files.  The
  36.                     following three cases may occur:
  37.  
  38.                     1. First, if rreeff is a null pointer, eellff__bbeeggiinn allocates
  39.                        a new ELF descriptor and prepares to process the
  40.                        entire file.  If the file being read is an archive,
  41.                        eellff__bbeeggiinn also prepares the resulting descriptor to
  42.                        examine the initial archive member on the next call
  43.                        to eellff__bbeeggiinn, as if the program had used eellff__nneexxtt or
  44.                        eellff__rraanndd to ``move'' to the initial member.
  45.  
  46.                     2. Second, if rreeff is a non-null descriptor associated
  47.                        with an archive file, eellff__bbeeggiinn lets a program
  48.                        obtain a separate ELF descriptor associated with an
  49.                        individual member.  The program should have used
  50.                        eellff__nneexxtt or eellff__rraanndd to position rreeff appropriately
  51.                        (except for the initial member, which eellff__bbeeggiinn
  52.                        prepares; see the example below).  In this case,
  53.                        ffiillddeess should be the same file descriptor used for
  54.                        the parent archive.
  55.  
  56.                     3. Finally, if rreeff is a non-null ELF descriptor that is
  57.                        not an archive, eellff__bbeeggiinn increments the number of
  58.                        activations for the descriptor and returns rreeff,
  59.                        without allocating a new descriptor and without
  60.                        changing the descriptor's read/write permissions.
  61.                        To terminate the descriptor for rreeff, the program
  62.                        must call eellff__eenndd once for each activation.  See
  63.                        eellff__nneexxtt(3E) and the EXAMPLES section for more
  64.                        information.
  65.  
  66.      EELLFF__CC__RREEAADD__MMMMAAPP
  67.                     This command duplicates the actions of EELLFF__CC__RREEAADD but
  68.                     uses the mmmmaapp() system call to access the file data in
  69.                     a more memory efficient manner.  If, after lliibbeellff has
  70.                     opened the file, another process truncates the file
  71.                     lliibbeellff could get a Segmentation Violation attempting to
  72.                     read data it believes is in the file (but which is no
  73.                     longer there due to the truncation).  Applications
  74.                     calling lliibbeellff with EELLFF__CC__RREEAADD__MMMMAAPP may therefore wish
  75.                     to install a signal handler for SSIIGGSSEEGGVV (Segmentation
  76.                     Violation) and issue a message when it happens.
  77.  
  78.      EELLFF__CC__RRDDWWRR     This command duplicates the actions of EELLFF__CC__RREEAADD and
  79.                     additionally allows the program to update the file
  80.                     image [see eellff__uuppddaattee(3E)].  That is, using EELLFF__CC__RREEAADD
  81.                     gives a read-only view of the file, while EELLFF__CC__RRDDWWRR
  82.                     lets the program read and write the file.  EELLFF__CC__RRDDWWRR
  83.                     is not valid for archive members.  If rreeff is non-null,
  84.                     it must have been created with the EELLFF__CC__RRDDWWRR command.
  85.  
  86.      EELLFF__CC__WWRRIITTEE    The program ignores previous file contents, presumably
  87.                     to create a new file.  rreeff is ignored for this command.
  88.  
  89.      EELLFF__CC__WWRRIITTEE__FFAASSTT
  90.                     This command is the same as EELLFF__CC__WWRRIITTEE except that
  91.                     instead of performing mmaalllloocc() on memory for the output
  92.                     file [and then doing a wwrriittee(2) and ffrreeee()],
  93.                     EELLFF__CC__WWRRIITTEE__FFAASSTT writes the output directly to the file
  94.                     system (by doing a wwrriittee as needed).  Avoiding running
  95.                     mmaalllloocc() can help limit time-consuming paging activity.
  96.  
  97.      eellff__bbeeggiinn Works on all files (including files with zero bytes),
  98.      providing it can allocate memory for its internal structures and read
  99.      any necessary information from the file.  Programs reading object
  100.      files thus may call eellff__kkiinndd or eellff__ggeetteehhddrr to determine the file type
  101.      (only object files have an ELF header).  If the file is an archive
  102.      with no more members to process, or an error occurs, eellff__bbeeggiinn returns
  103.      a null pointer.  Otherwise, the return value is a non-null ELF
  104.      descriptor.
  105.  
  106.      Before the first call to eellff__bbeeggiinn, a program must call eellff__vveerrssiioonn to
  107.      coordinate versions.
  108.  
  109. SSyysstteemm SSeerrvviicceess
  110.      When processing a file, the library decides when to read or write the
  111.      file, depending on the program's requests.  Usually, the library
  112.      assumes the file descriptor remains usable for the life of the ELF
  113.      descriptor.  If, however, a program must process many files
  114.      simultaneously and the underlying operating system limits the number
  115.      of open files, the program can use eellff__ccnnttll to let it reuse file
  116.      descriptors.  After calling eellff__ccnnttll with appropriate arguments, the
  117.      program may close the file descriptor without interfering with the
  118.      library.
  119.  
  120.      All data associated with an ELF descriptor remain allocated until
  121.      eellff__eenndd terminates the descriptor's last activation.  After the
  122.      descriptors have been terminated, the storage is released; attempting
  123.      to reference such data gives undefined behavior.  Consequently, a
  124.      program that deals with multiple input (or output) files must keep the
  125.      ELF descriptors active until it finishes with them.
  126.  
  127. EEXXAAMMPPLLEESS
  128.      Example 1:  The following is a prototype for reading a file.  If the
  129.      file is a simple object file, the program executes the loop one time,
  130.      receiving a null descriptor in the second iteration.  In this case,
  131.      both eellff and aarrff will have the same value, the activation count will
  132.      be two, and the program calls eellff__eenndd twice to terminate the
  133.      descriptor.  If the file is an archive, the loop processes each
  134.      archive member in turn, ignoring those that are not object files.
  135.  
  136.           if (elf_version(EV_CURRENT) == EV_NONE)
  137.           {
  138.                /* library out of date */
  139.                /* recover from error */
  140.           }
  141.           cmd = ELF_C_READ;
  142.           arf = elf_begin(fildes, cmd, (Elf *)0);
  143.           while ((elf = elf_begin(fildes, cmd, arf)) != 0)
  144.           {
  145.                if ((ehdr = elf32_getehdr(elf)) != 0)
  146.                {
  147.                     /* process the file ... */
  148.                }
  149.                cmd = elf_next(elf);
  150.                elf_end(elf);
  151.           }
  152.           elf_end(arf);
  153.  
  154.      Example 2:  Alternatively, the next example illustrates random archive
  155.      processing.  After identifying the file as an archive, the program
  156.      repeatedly processes archive members of interest.  For clarity, this
  157.      example omits error checking and ignores simple object files.
  158.      Additionally, this fragment preserves the ELF descriptors for all
  159.      archive members, because it does not call eellff__eenndd to terminate them.
  160.  
  161.           elf_version(EV_CURRENT);
  162.           arf = elf_begin(fildes, ELF_C_READ, (Elf *)0);
  163.           if (elf_kind(arf) != ELF_K_AR)
  164.           {
  165.                /* not an archive */
  166.           }
  167.           /* initial processing */
  168.           /* set offset = ... for desired member header */
  169.           while (elf_rand(arf, offset) == offset)
  170.           {
  171.                if ((elf = elf_begin(fildes, ELF_C_READ, arf)) == 0)
  172.                     break;
  173.                if ((ehdr = elf32_getehdr(elf)) != 0)
  174.                {
  175.                     /* process archive member ... */
  176.                }
  177.                /* set offset = ... for desired member header */
  178.           }
  179.  
  180.      Example 3:  The following outline shows how you might create a new ELF
  181.      file.  This example is simplified to show the overall flow.
  182.  
  183.           elf_version(EV_CURRENT);
  184.           fildes = open("path/name", O_RDWR|O_TRUNC|O_CREAT, 0666);
  185.           if ((elf = elf_begin(fildes, ELF_C_WRITE, (Elf *)0)) == 0)
  186.                return;
  187.           ehdr = elf32_newehdr(elf);
  188.           phdr = elf32_newphdr(elf, count);
  189.           scn = elf_newscn(elf);
  190.           shdr = elf32_getshdr(scn);
  191.           data = elf_newdata(scn);
  192.           elf_update(elf, ELF_C_WRITE);
  193.           elf_end(elf);
  194.  
  195.      Example 4:  The following outline shows how you might update an
  196.      existing ELF file.  This example is simplified to show the overall
  197.      flow.
  198.  
  199.           elf_version(EV_CURRENT);
  200.           fildes = open("path/name", O_RDWR);
  201.           elf = elf_begin(fildes, ELF_C_RDWR, (Elf *)0);
  202.  
  203.           /* add new or delete old information ... */
  204.  
  205.           close(creat("path/name", 0666));
  206.           elf_update(elf, ELF_C_WRITE);
  207.           elf_end(elf);
  208.  
  209.      In the previous example, the call to ccrreeaatt truncates the file, thus
  210.      ensuring the resulting file will have the ``right'' size.  Without
  211.      truncation, the updated file might be as big as the original, even if
  212.      information were deleted.  The library truncates the file, if it can,
  213.      with ffttrruunnccaattee [see ttrruunnccaattee(2)].  Some systems, however, do not
  214.      support ffttrruunnccaattee, and the call to ccrreeaatt protects against this.
  215.  
  216.      Note that both file creation examples open the file with write and
  217.      read permissions.  The library is not compiled to use mmmmaapp so there is
  218.      no need for write permission.  But for maximum portability with
  219.      implementations that do use mmmmaapp for file creation, you may want to
  220.      provide both write and read permissions.
  221.  
  222. NNOOTTEESS
  223.      COFF is an object file format that preceded ELF.  COFF object files
  224.      cannot be used with this library.
  225.  
  226.      EELLFF__CC__RREEAADD__MMMMAAPP and EELLFF__CC__WWRRIITTEE__FFAASSTT are options specific to this
  227.      implementation, not options that are generally available.
  228.  
  229. SSEEEE AALLSSOO
  230.      ccrreeaatt(2), llsseeeekk(2), mmmmaapp(2), ooppeenn(2), ttrruunnccaattee(2), eellff(3E),
  231.      eellff__ccnnttll(3E), eellff__eenndd(3E), eellff__ggeettaarrhhddrr(3E), eellff__ggeettbbaassee(3E),
  232.      eellff__ggeettddaattaa(3E), eellff__ggeetteehhddrr(3E), eellff__ggeettpphhddrr(3E), eellff__ggeettssccnn(3E),
  233.      eellff__kkiinndd(3E), eellff__nneexxtt(3E), eellff__rraanndd(3E), eellff__rraawwffiillee(3E),
  234.      eellff__uuppddaattee(3E), eellff__vveerrssiioonn(3E), aarr(4)
  235.  
  236.      This man page is available only online.
  237.